昨天我們示範了如何產生及檢視文件。
今天除了介紹文件裡面的內容，也會說明如何加入 model 以及欄位的說明。

開發區和正式區的 Documentation，版面完全相同。
但若我們的做的異動，還沒有提交到 GitHub 並 merge to the main branch，並重跑 Job，就不會呈現在正式區的文件。
為了避免混淆，接下來我們都會使用開發環境來說明。

文件內容

文件主要有 Project 和 Database 兩個頁籤。
Database 頁籤其實就是 Database 物件檢視，包含 databases, datasets, tables/views，在此不多作說明。

Project tab

Project 頁籤點進去，可以看到上下兩塊：Sources 和 Project。

上方區塊的 Sources，以此專案來說，資料源指的就是 dbt tutorial，官方提供的 BigQuery datasets。
包含 customers 以及 orders 兩個資料表。

下方區塊的 Project 才是我們的 dbt 專案。

以 customer model 為例

若點進 customer model 之後可以看到...

Details: model 的基本資訊
Description: model 的說明。

Columns: 自動產生的欄位列表，包含欄位名稱及欄位型態。

DAY 08 加入的 tests 也有包含在文件。

點 more 的小箭頭可以展開。

Referenced By: 參考到此 model 的物件，也就是此 model 的下游。
Depends On: 此 model 參考到的物件，也就是上游。

Code: 也就是定義此 model 的語法，又分為 source 和 compiled 兩個頁籤。

Lineage Graph

點開右下角藍綠色的 View Lineage Graph，可以看到上下游的圖形化關係。

再點右上角的 View Fullscreen 可以展開。

編輯文件，加入 model 以及欄位的說明

現在我們要回到 DAY 08 加入 tests 時，所新增的 models/schema.yml，加入 model 及欄位的 description。

如下圖綠色處，只要在 model 名稱及 column 名稱下面新增一行 description，就可以加入說明，例如：

• model customers: One record per customer
• customers.customer_id: Primary key
  

更新完的內容如下，可以直接貼過去用。
原始來源：https://docs.getdbt.com/quickstarts/bigquery?step=13

version: 2

models:
  - name: customers
    description: One record per customer
    columns:
      - name: customer_id
        description: Primary key
        tests:
          - unique
          - not_null
      - name: first_order_date
        description: NULL when a customer has not yet placed an order.

  - name: stg_customers
    description: This model cleans up customer data
    columns:
      - name: customer_id
        description: Primary key
        tests:
          - unique
          - not_null

  - name: stg_orders
    description: This model cleans up order data
    columns:
      - name: order_id
        description: Primary key
        tests:
          - unique
          - not_null
      - name: status
        tests:
          - accepted_values:
              values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']
      - name: customer_id
        tests:
          - not_null
          - relationships:
              to: ref('stg_customers')
              field: customer_id

接下來，我們執行一次 dbt docs generate 確認一下更新後的文件，可以看到說明都已經加上去了。

今日小結＆明日預告

今日深入介紹了文件的內容，並示範如何將 model 及欄位的說明加入文件。
雖然手動編輯需要一些力氣，但只要能藉此提昇團隊協作的效率，我相信一切都會值得的。

最後，提交今日的變更，結束這一天。

明天的主題：dbt Seeds，如果有手動維護的 mapping table，可以使用 seed 的功能。

參考資料

• Quickstart for dbt Cloud and BigQuery https://docs.getdbt.com/quickstarts/bigquery
• About documentation https://docs.getdbt.com/docs/collaborate/documentation

歡迎加入 dbt community
對 dbt 或 data 有興趣 👋？歡迎加入 dbt community 到 #local-taipei 找我們，也有實體 Meetup 請到 dbt Taipei Meetup 報名參加